#Clean Code

作者：给立乐*
出处：http://spencer-dev.com/2016/11/19/Clean Code - Chapter 5 格式
声明：本文采用以下协议进行授权：自由转载-非商用-非衍生-保持署名|Creative Commons BY-NC-ND 3.0 ，转载请注明作者及出处。

当有人查看底层代码实现时，我们希望他们为其整洁、一致及所感知到的对细节的关注而震惊。我们希望他们高高扬起眉毛、一路看下去。我们希望他们感受到那些为之劳作的专业人士们。但若他们看到的只是一堆像是由酒醉的水手写出的鬼画符，那它们多半会得出结论，认为项目其他任何部分也同样对细节漠不关心。

你应该保持良好的代码格式。你应该选用一套管理代码格式的简单规则，然后贯彻这些规则。如果你在团队中工作，则团队应该一致同意采用一套简单的格式规则，所有成员都要遵从。

格式的目的

先明确一下，代码格式很重要。代码格式不可忽略，必须严肃对待。代码格式关乎沟通，而沟通是专业开发者的头等大事。

或许你认为“让代码能工作”才是专业开发者的头等大事。然而，我希望本书能让你跑掉那种想法。你今天编写的功能，极有可能在下一版本中被修改，但代码的可读性却会对以后可能发生的修改行为产生深远的影响。原始代码修改之后很久，其代码风格和可读性仍会影响到可维护性和拓展型。即便代码已经不复存在，你的风格和律条仍存活下来。

垂直格式

源代码文件该有多大？在 Java 中，文件尺寸与类尺寸及其相关。讨论类的时候再说类的尺寸。现在先考虑文件尺寸。

多数 Java 源代码文件有多大？事实说明，尺寸各不相同，长度殊异。

Junit、FitNesse 和 Time and Money 由相对较小的文件组成。没有一个超过500行，多数都小于200行。Tomcat 和 Ant 则有些文件达到数千行，将近一半文件长于200行。对我们来说，这意味着什么？意味着有可能用大多数为200行、最长500行的单个文件构造出色的系统（ FitNesse 总长约50000行）。尽管这并非不可违背的原则，也应该乐于接受。短文件通常比长文件易于理解。

向报纸学习

源文件也要像报纸文章那样。名称应当简单且一目了然。名称本身应该足够告诉我们是否在正确的模块中。源文件最顶部应该给出高层次概念和算法。细节应该往下渐次展开，直至找到源文件中最底层的函数和细节。

概念间垂直方向上的区隔

几乎所有的代码都是从上往下读，从左往右读。每行展现一个表达式或一个子句，每组代码行展示一条完整的思路。这些思路用空白行区隔开来。

垂直方向上的靠近

如果说空白行隔开了概念，靠近的代码行则暗示了它们之间的紧密关系。所以，紧密相关的代码应该互相靠近。

垂直距离

你是否曾经在某个类中摸索，从一个函数跳到另一个函数，上下求索，想要弄清楚这些函数如何操作、如何互相相关，最后却被搞糊涂了？你是否曾经苦苦追索某个变量或函数的继承链条？这让人沮丧，因为你想要理解系统做什么，但却花时间和精力在找到和记住那些代码碎片在哪里。

关系密切的概念应该互相靠近。显然，这条规则并不适用于分布在不同文件中的概念。除非有很好的理由，否则就不要把关系密切的概念放到不同的文件中。实际上，这也是避免使用 protected 变量的理由之一。

对于那些关系密切、放置于同一源文件中的概念，它们之间的区隔应该成为对相互的易懂度有多重要的衡量标准。应避免迫使读者在源文件和类中跳来跳去。

变量声明

变量声明应尽可能靠近其使用位置。因为函数很短，本地变量应该在函数的顶部出现。

循环中的控制变量应该总是在循环语句中声明。

偶尔，在较长的函数中，变量也可能在某个代码块顶部，或在循环之前声明。

实体变量应该在类的顶部声明。这应该不会增加变量的垂直距离，因为在设计良好的类中，它们如果不是被该类的所有方法也是被大多数方法所用。

关于实体变量应该放在哪里，争论不断。在 C++ 中，通常会采用所谓“剪刀原则”（scissors rule），所有实体变量都放在底部。而在 Java 中，惯例是放在类的顶部。没理由去遵循其他惯例。重点是在谁都知道的地方声明实体变量。大家都应该知道在哪儿能看到这些声明。

概念相关

概念相关的代码应该放到一起。相关性越强，彼此之间的距离就该越短。如上所述，相关性应建立在直接依赖的基础上，如函数间调用，或函数使用某个变量。但也有其他相关性的可能。相关性可能来自于执行相似操作的一组函数。

垂直顺序

一般而言，我们想自上向下展示函数调用依赖顺序。也就是说，被调用的函数应该放在执行调用的函数下面。这样就建立了一种自顶向下贯穿源代码模块的良好信息流。

像报纸文章一般，我们指望最重要的概念先出来，指望以包括最少细节的方式表述它们。我们指望底层细节最后出来。这样，我们就能扫过源代码文件，自最前面的几个函数获知要旨，而不至于沉溺到细节中。

横向格式

一行代码应该有多宽？

应该尽力保持代码行短小。死守80个字符的上限有点僵化，而且我也并不反对代码行长度达到100个字符或120个字符。再多的话，大抵就是肆意妄为了。

我一向遵循无需拖动滚动条到右边的原则。但近年来显示器越来越宽，而年轻程序员又能将显示字符缩小到如此程度，屏幕上甚至能容纳200个字符的宽度。别那么做。我个人的上限是120个字符。

团队规则

每个程序员都有自己喜欢的格式规则，但如果在一个团队中工作，就是团队说了算。

一组开发者应当认同一种格式风格，每个成员都应该采用那种风格。我们想要让软件拥有一以贯之的风格。我们不想让它显得是由一大票意见相左的个人所写成。

记住，好的软件系统是由一系列读起来不错的代码文件组成的。它们需要拥有一致和顺畅的风格。读者要能确信，他们在一个源文件中看到的格式风格在其他文件中也是同样的用法。绝对不要用各种不同的风格来编写源代码，这样会增加其复杂度。

鲍勃大叔的格式规则

public class CodeAnalyzer implements JavaFileAnalysis {
  private int lineCount;
  private int maxLineWidth;
  private int widestLineNumber;
  private LineWidthHistogram lineWidthHistogram;
  private int totalChars;
  public CodeAnalyzer() {
    lineWidthHistogram = new LineWidthHistogram();
  }
  public static List<File> findJavaFiles(File parentDirectory) {
    List<File> files = new ArrayList<File>();
    findJavaFiles(parentDirectory, files);
    return files;
  }
  private static void findJavaFiles(File parentDirectory, List<File> files) {
    for (File file : parentDirectory.listFiles()) {
      if (file.getName().endsWith(".java"))
        files.add(file);
      else if (file.isDirectory())
        findJavaFiles(file, files);
    }
  }
  public void analyzeFile(File javaFile) throws Exception {
    BufferedReader br = new BufferedReader(new FileReader(javaFile));
    String line;
    while ((line = br.readLine()) != null)
      measureLine(line);
  }
  private void measureLine(String line) {
    lineCount++;
    int lineSize = line.length();
    totalChars += lineSize;
    lineWidthHistogram.addLine(lineSize, lineCount);
    recordWidestLine(lineSize);
  }
  private void recordWidestLine(int lineSize) {
    if (lineSize > maxLineWidth) {
      maxLineWidth = lineSize;
      widestLineNumber = lineCount;
    }
  }
  public int getLineCount() {
    return lineCount;
  }
  public int getMaxLineWidth() {
    return maxLineWidth;
  }
  public int getWidestLineNumber() {
    return widestLineNumber;
  }
  public LineWidthHistogram getLineWidthHistogram() {
    return lineWidthHistogram;
  }
  public double getMeanLineWidth() {
    return (double)totalChars / lineCount;
  }
  public int getMedianLineWidth() {
    Integer[] sortedWidths = getSortedWidths();
    int cumulativeLineCount = 0;
    for (int width : sortedWidths) {
      cumulativeLineCount += lineCountForWidth(width);
      if (cumulativeLineCount > lineCount / 2)
        return width;
    }
    throw new Error("Cannot get here");
  }
  private int lineCountForWidth(int width) {
    return lineWidthHistogram.getLinesforWidth(width).size();
  }
  private Integer[] getSortedWidths() {
    Set<Integer> widths = lineWidthHistogram.getWidths();
    Integer[] sortedWidths = (widths.toArray(new Integer[0]));
    Arrays.sort(sortedWidths);
    return sortedWidths;
  }
}
interface JavaFileAnalysis {
}
class LineWidthHistogram {
  public void addLine(int lineSize, int lineCount) {
  }
  public Attributes getLinesforWidth(int width) {
    return null;
  }
  public Set<Integer> getWidths() {
    return null;
  }
}

Clean Code - Chapter 5 格式